Docs: Rename Block Hooks handbook page to Block Filters #54862
Conversation
ockham
requested review from
ryanwelcher,
juanmaguitar,
fabiankaegy and
ndiego
as code owners
|
LGTM! 👍 |
Ah, good point! Done in 9b1bcdf. |
| @@ -18,7 +18,7 @@ | |||
|
|
|||
| ## [Hooks Reference](/docs/reference-guides/filters/README.md) | |||
There was a problem hiding this comment.
Should we also rename this to "Hooks and Filters Reference" now? Ripple effects... 😬
| ## [Hooks Reference](/docs/reference-guides/filters/README.md) | |
| ## [Hooks and Filters Reference](/docs/reference-guides/filters/README.md) |
There was a problem hiding this comment.
In theory, the concept "Hooks" would already include "Filters" (and "Actions") so I think the current two changes are enough for now for the purpose of this PR.
We can think later of a better way to name these Reference API pages
ockham
deleted the
rename/block-hooks-handbook-page-to-block-filters
branch
|
Merged.
|
|
Yeah it updates every 15 minutes. |
|
I led the effort to consolidate documentation pages explaining the usage of WordPress hooks with the editor at #42356. It doesn't always cover filters like it was called previously, so we decided to unify the vocabulary to follow WordPress core: https://developer.wordpress.org/plugins/hooks/ It's also grouped under the "hooks" in the code reference: https://developer.wordpress.org/reference/hooks/ The biggest difference between Gutenberg and WordPress core is that for core the documentation is generated from the source code, it's searchable, and based on individual use cases. On the contrary, only a subset of WordPress hooks available are documented in the block editor because it has to be done manually. If we were to follow WP core, then the issue wouldn't exist as we wouldn't have to divide filters and actions based on their role arbitrarily. In conclusion, the phrase Block Hooks is confusing here, and Block Filters is a good short-term solution, but it's the issue that we have to manually maintain code references for WordPress hooks used with the editor. |
What?
Rename the handbook page currently entitled "Block Hooks" to "Block Filters".
Why?
To distinguish from the new "Block Hooks" feature, which is conceptually very different.
How?
By renaming the handbook page from "Block Hooks" to "Block Filters".
AFAICT, the handbook page makes no direct reference to hooks, other than the title; furthermore, the relevant client-side
@wordpress/package happens to be called@wordpress/hooks. Reading the page, it’s all about filters though (both on the client and server sides), whereas "hooks" traditionally denotes the union of filters and actions — the latter of which are pretty much absent from the page.Finally, note that the filename has already been
block-filters.mdbefore.Thus, changing the title to "Block Filters" seems warranted.
Flagged by @juanmaguitar in Slack.